Java Database Programming with JDBC Java Database Programming with JDBC
by Pratik Patel
Coriolis, The Coriolis Group
ISBN: 1576100561   Pub Date: 10/01/96
  

Previous Table of Contents Next


Listing 10.15 Using the getPropertyInfo method to identify properties at runtime.

import java.sql.*;

class PropertyTest {

    public static void main(String args[])
    {
        try {

            // Quick way to create a driver object
              java.sql.Driver d = new jdbc.SimpleText.SimpleTextDriver();

            String url = "jdbc:SimpleText";
            // Make sure we have the proper URL
               if (!d.acceptsURL(url)) {
                throw new SQLException("Unknown URL: " + url);
            }

            // Setup a Properties object. This should contain an entry
             // for all known properties to this point. Properties that
             // have already been specified in the Properties object will
             // not be returned by getPropertyInfo.
            java.util.Properties props = new java.util.Properties();

            // Get the property information
            DriverPropertyInfo info[] = d.getPropertyInfo(url, props);

          // Just dump them out
              System.out.println("Number of properties: " + info.length);

            for (int i=0; i < info.length; i++) {
                 System.out.println("\nProperty " + (i + 1));
                System.out.println("Name:        " + info[i].name);
                 System.out.println("Description: " +
                   info[i].description);
                  System.out.println("Required:    " + info[i].required);
                System.out.println("Value:       " + info[i].value);
                 System.out.println("Choices:     " + info[i].choices);
            }

        }
        catch (SQLException ex) {
               System.out.println ("\nSQLException(s) caught\n");

            // Remember that SQLExceptions may be chained together
              while (ex != null) {
                     System.out.println("SQLState: " + ex.getSQLState());
                    System.out.println("Message:  " + ex.getMessage());
                     System.out.println ("");
                   ex = ex.getNextException ();
            }
        }
    }
}

Listing 10.15 produces the following output:

Number of properties: 1

Property 1
Name:        Directory
Description: Initial text file directory
Required:    false
Value:       null
Choices:     null

It doesn’t take a lot of imagination to envision an application or applet that gathers the property information and prompts the user in order to connect to the database. The actual code to implement the getPropertyInfo method for the SimpleText driver is very simple, as shown in Listing 10.16.

Listing 10.16 Implementing the getPropertyInfo method.

//------------------------------------------------------------------------
// getPropertyInfo - JDBC API
//
// The getPropertyInfo method is intended to allow a generic GUI tool to
// discover what properties it should prompt a human for in order to get
// enough information to connect to a database. Note that depending on
// the values the human has supplied so far, additional values may become
// necessary, so it may be necessary to iterate though several calls.
// to getPropertyInfo.
//
//    url        The URL of the database to connect to.
//
//    info    A proposed list of tag/value pairs that will be sent on
//            connect open.
//
// Returns an array of DriverPropertyInfo objects describing possible
//            properties. This array may be an empty array if no
//            properties are required.
//------------------------------------------------------------------------

public   DriverPropertyInfo[] getPropertyInfo(
      String url,
       java.util.Properties info)
     throws SQLException
{
      DriverPropertyInfo prop[];
     // Only one property required for the SimpleText driver, the
     // directory. Check the property list coming in. If the
     // directory is specified, return an empty list.
      if (info.getProperty("Directory") == null) {

        // Setup the DriverPropertyInfo entry
        prop = new DriverPropertyInfo[1];
          prop[0] = new DriverPropertyInfo("Directory", null);
            prop[0].description = "Initial text file directory";
        prop[0].required = false;

    }
    else {
        // Create an empty list
         prop = new DriverPropertyInfo[0];
    }

    return prop;

}

Let’s Get Connected

Now that we can identify a driver to provide services for a given URL and get a list of the required and optional parameters necessary, it’s time to establish a connection to the database. The connect method does just that, as shown in Listing 10.17, by taking a URL and connection property list and attempting to make a connection to the database. The first thing that connect should do is verify the URL (by making a call to acceptsURL). If the URL is not supported by the driver, a null value will be returned. This is the only reason that a null value should be returned. Any other errors during the connect should throw an SQLException.

Listing 10.17 Connecting to the database.

//------------------------------------------------------------------------
// connect - JDBC API
//
// Try to make a database connection to the given URL.
// The driver should return "null" if it realizes it is the wrong kind
// of driver to connect to the given URL. This will be common, as when
// the JDBC driver manager is asked to connect to a given URL, it passes
// the URL to each loaded driver in turn.
//
// The driver should raise an SQLException if it is the right
// driver to connect to the given URL, but has trouble connecting to
// the database.
//
// The java.util.Properties argument can be used to pass arbitrary
// string tag/value pairs as connection arguments.
// Normally, at least "user" and "password" properties should be
// included in the Properties.
//
//    url    The URL of the database to connect to.
//
//     info    a list of arbitrary string tag/value pairs as
//             connection arguments; normally, at least a "user" and
//             "password" property should be included.
//
// Returns a Connection to the URL.
//------------------------------------------------------------------------
public Connection connect(
      String url,
       java.util.Properties info)
    throws SQLException
{
    if (traceOn()) {
          trace("@connect (url=" + url + ")");
    }

    // Ensure that we can understand the given URL
     if (!acceptsURL(url)) {
          return null;
    }

    // For typical JDBC drivers, it would be appropriate to check
   // for a secure environment before connecting, and deny access
   // to the driver if it is deemed to be unsecure. For the
    // SimpleText driver, if the environment is not secure, we will
    // turn it into a read-only driver.

   // Create a new SimpleTextConnection object
    SimpleTextConnection con = new SimpleTextConnection();

     // Initialize the new object. This is where all of the
    // connection work is done.
    con.initialize(this, info);
 
   return con;
}


Previous Table of Contents Next